Transactions List

Retrieve a list of your institution's wallet top-up transactions, newest first.

info

Use this endpoint to reconcile your records with Presto or to check the status of many transactions at once. To check one transaction by its reference, use the Transaction Status endpoint.

Overview

The transactions list endpoint returns the wallet top-up transactions your institution created, filtered by status and creation date. Results are split into pages, and you move between pages with a cursor.

You only ever see your own institution's transactions.

Endpoint Details

Method: GET
URL: /api/institutions/v1/wallet/transactions
Purpose: Retrieve a paginated list of your wallet top-up transactions

Authentication Required

All API calls, including transactions list requests, require a valid authentication token in the Authorization header.

Request Specification

Query Parameters

Parameter	Type	Required	Description
status	string	No	Only return transactions with this status: pending, completed, or failed. Returns every status when omitted
from	string	No	First day to include, in YYYY-MM-DD format. Defaults to 30 days before to
to	string	No	Last day to include, in YYYY-MM-DD format. Defaults to today
per_page	integer	No	Number of transactions per page. Defaults to 20. Values above 100 return 100
cursor	string	No	Position of the page to return. Take it from meta.next_cursor or meta.prev_cursor of the previous response

Date Range

• from and to filter on the date the transaction was created. Both days are included.
• Days are in UTC.
• The range can be at most 90 days. A longer range returns 422.
• With no dates, you get the last 30 days.

Example Request

GET /api/institutions/v1/wallet/transactions?status=completed&from=2026-10-01&to=2026-10-21&per_page=50
Authorization: Bearer {token}

Response Specification

Success Response

200 OK

{
  "data": [
    {
      "transaction_reference": "TRX987654323",
      "status": "completed",
      "amount": 50,
      "currency": "LYD",
      "created_at": "2026-10-21T09:12:04+00:00",
      "customer": {
        "name": "Moh... Ali...",
        "country_code": "LY",
        "phone": "928569313"
      }
    },
    {
      "transaction_reference": "TRX987654322",
      "status": "failed",
      "amount": 20,
      "currency": "LYD",
      "created_at": "2026-10-20T16:45:10+00:00",
      "customer": {
        "name": "Ahm... Sal...",
        "country_code": "LY",
        "phone": "918877665"
      }
    },
    {
      "transaction_reference": "TRX987654321",
      "status": "pending",
      "amount": 100,
      "currency": "LYD",
      "created_at": "2026-10-20T11:02:57+00:00",
      "customer": {
        "name": "Fat... Omr...",
        "country_code": "LY",
        "phone": "945566778"
      }
    }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https://{host}/api/institutions/v1/wallet/transactions?per_page=3&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0yMCAxMTowMjo1NyIsImlkIjozODksIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  },
  "meta": {
    "path": "https://{host}/api/institutions/v1/wallet/transactions",
    "per_page": 3,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0yMCAxMTowMjo1NyIsImlkIjozODksIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null
  }
}

Response Fields

Field	Type	Description
data	array	The transactions on this page, newest first
data[].transaction_reference	string	Unique identifier for the transaction
data[].status	string	"pending", "completed", or "failed" (see Statuses)
data[].amount	number	The top-up amount
data[].currency	string	Currency code for the amount
data[].created_at	string	ISO 8601 date and time when the transaction was created
data[].customer	object	The customer whose wallet the top-up is for, or null if the customer account no longer exists
data[].customer.name	string	Partially masked customer name
data[].customer.country_code	string	Country code (or "LY" if not set)
data[].customer.phone	string	Customer phone number
links.next	string	URL of the next page, or null on the last page
links.prev	string	URL of the previous page, or null on the first page
links.first, links.last	null	Always null. Cursor pagination has no fixed first or last page
meta.path	string	URL of this endpoint
meta.per_page	integer	Number of transactions per page
meta.next_cursor	string	Cursor of the next page, or null on the last page
meta.prev_cursor	string	Cursor of the previous page, or null on the first page

Statuses

Status	Meaning
pending	The top-up has started but is not complete yet
completed	The customer's wallet has been credited
failed	The top-up was cancelled

The status in this list is always the same as the status the Transaction Status endpoint returns for that transaction.

Pagination

To read every transaction in a date range:

1. Call the endpoint with your filters.
2. If links.next is not null, request that URL. It already includes your filters and the cursor.
3. Repeat until links.next is null.

New transactions created while you are paging do not move the transactions on the pages that follow, so you will not see a transaction twice or miss one.

Error Responses

401 Unauthorized - Authentication issues

{
  "message": "Unauthenticated."
}

422 Unprocessable Content - Date range longer than 90 days

{
  "message": "The date range cannot be longer than 90 days.",
  "errors": {
    "to": ["The date range cannot be longer than 90 days."]
  }
}

422 Unprocessable Content - to is before from

{
  "message": "The to date must be on or after the from date.",
  "errors": {
    "to": ["The to date must be on or after the from date."]
  }
}

422 Unprocessable Content - Invalid parameters

{
  "message": "The from does not match the format Y-m-d. (and 1 more error)",
  "errors": {
    "from": ["The from does not match the format Y-m-d."],
    "per_page": ["The per page must be at least 1."]
  }
}

Error Handling

Common Errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
401	Unauthorized	{"message": "Unauthenticated."}	Missing or invalid authentication token. Provide a valid token.
422	Date range too long	{"message": "The date range cannot be longer than 90 days."}	from and to are more than 90 days apart. Split the range into smaller ranges.
422	Dates in wrong order	{"message": "The to date must be on or after the from date."}	to is before from. Swap the dates.
422	Validation error	{"message": "The from does not match the format Y-m-d."}	A parameter has an invalid value. Check the query parameters.

Use Cases

This endpoint is particularly useful for:

1. Reconciliation - Compare your daily or monthly records with Presto
2. Missing References - Find transactions whose reference you did not store
3. Status Checks - Check the status of many transactions with one call per page
4. Auditing - Export transaction records for compliance

Implementation Tips

Best Practices

• For a range longer than 90 days, make one request per 90-day range
• Follow links.next instead of building page URLs yourself
• Use per_page=100 when you read many pages, to make fewer calls
• Use the Transaction Status endpoint when you only need one transaction